home *** CD-ROM | disk | FTP | other *** search
/ Pascal Super Library / Pascal Super Library (CW International)(1997).bin / STRINGS / SHLNGST1 / SHLNGSTR.DOC next >
Text File  |  1991-03-09  |  39KB  |  1,680 lines
  1.  
  2.  
  3.  
  4.                                   ShLngStr
  5.  
  6.        A LongString Manipulation Unit for Turbo Pascal 5.0 and above.
  7.                         (A SkyHawk development tool)
  8.  
  9.                                      by
  10.  
  11.                      W. G. Madison and Associates, Ltd.
  12.                             8425 Greenbelt Road
  13.                                 P.O. Box 898
  14.                             Greenbelt, MD 20770
  15.                                (301)552-7234
  16.                                CIS 73240,342
  17.  
  18.                     Copyright 1991 Madison & Associates
  19.                             All Rights Reserved
  20.  
  21.           This unit  and the associated .DOC and TEST.* files may
  22.           be freely copied and distributed, provided only that no
  23.           fee is charged for the package beyond a nominal copying
  24.           charge, and provided that the package is distributed IN
  25.           UNALTERED FORM. The sole exception to  this  latter re-
  26.           striction is that bona-fide clubs and  user  groups may
  27.           append text material to  the  documentation  file, pro-
  28.           vided that any  material appended is clearly identified
  29.           as to its source, its beginning, and its end.
  30.  
  31.  
  32.  
  33.      INTRODUCTION
  34.  
  35.           ShLngStr is a unit which provides the ability to manipulate
  36.      long strings (up to 65517 characters in length) using Turbo Pas-
  37.      cal. As such, it owes a debt to the Tp/OpASCIIZ units published
  38.      by TurboPower Software. Unlike the ASCIIZ manipulation units,
  39.      however, it carries its dynamic string length information in a
  40.      WORD at the beginning of the string. As such, it owes a debt to
  41.      the TpWrdStr unit written by Ken Henderson.
  42.  
  43.           Both TpWrdStr and Tp/OpASCIIZ require a careful tradeoff on
  44.      the part of the user. They both typically allocate an "array of
  45.      char" in the data segment, in which the string data are stored;
  46.      thus they both define a MaxSize constant which must be carefully
  47.      balanced between providing a maximum string length long enough to
  48.      get the job done, and one which is small enough to avoid using up
  49.      the entire data segment.
  50.  
  51.           ShLngStr avoids this problem. ShLngStr stores all of its
  52.      string data on the heap. When a variable is declared to be of
  53.      type LongString, this declaration establishes only a pointer in
  54.      the data segment. The LongString must then be initialized prior
  55.  
  56.  
  57.  
  58.      to use. This initialization establishes a maximum allowable
  59.      string length, which may now vary from one LongString to the
  60.      next. Only the amount of heap space required for the initialized
  61.      maximum length is used. In this respect, the analog of a string
  62.      declaration of, for example, "var string[127];" has been pre-
  63.      served. Any of the procedures and functions in this unit will
  64.      observe the "declared" maximum length, and will adjust their
  65.      behavior appropriately
  66.  
  67.           Thus, although a MaxLongString constant is included in the
  68.      unit, its value is set to the maximum allowable value (65517) and
  69.      is used only by lsInit.
  70.  
  71.           Notwithstanding any of the above, the code in ShLngStr is
  72.      completely our own. Any bugs or deficiencies cannot be blamed on
  73.      anyone other than Madison & Associates.
  74.  
  75.  
  76.      PROCEDURE AND FUNCTION CALLS
  77.  
  78.           There are currently approximately 80 procedures and func-
  79.      tions available within the ShLngStr unit. With few exceptions,
  80.      each procedure has a corresponding function; e.g., procedure
  81.      lsStr2LongString which converts a string to a LongString has a
  82.      corresponding function lsStr2LongStringF. It is important to
  83.      remember that the functions which return a LongString are return-
  84.      ing a pointer value rather than the contents of the LongString
  85.      itself. Failure to account for this can result in rather startl-
  86.      ing results on occasion.
  87.  
  88.           Function results (i.e., these pointers) are stored in a ring
  89.      buffer which is allocated as needed, and is only reallocated when
  90.      the ring pointer comes back around to the specific element. By
  91.      default, the number of elements in the ring is set to 25. This
  92.      should be sufficient for most purposes; should it prove insuffi-
  93.      cient, set the typed constant RingSize to a larger value and re-
  94.      compile. Alternatively, RingSize can be increased at execution
  95.      time to a maximum value of 100; it should NOT be decreased at
  96.      execution time, however. It can be set to a maximum of 100
  97.      without affecting the size of the data segment.
  98.  
  99.           Since the data associated with function (pointer) returns
  100.      are accessible only through elements in the ring buffer, and
  101.      since the heap space used to store these data will be released
  102.      when the ring element is required for reuse, it is important that
  103.      these data be used as quickly as possible. It ain't gonna be
  104.      around forever!
  105.  
  106.           Thus, the rule of thumb should be "when in doubt, use
  107.      procedure calls."
  108.  
  109.  
  110.  
  111.  
  112.                                    - 2 -
  113.  
  114.  
  115.  
  116.      CONSTANTS
  117.  
  118.        MaxLongString = 65517;
  119.  
  120.           The maximum length of a LongString.
  121.      ______________________________
  122.  
  123.        NotFound = 0;
  124.  
  125.           Returned by the lsPos functions if a substring is not found.
  126.  
  127.  
  128.      TYPES
  129.  
  130.        LongStringType  = record
  131.                            Length,           {The dynamic length}
  132.                            dLength : word;   {The "declared" length}
  133.                            lsData  : array[1..1] of char;
  134.                            end;
  135.  
  136.           The record structure allocated on the heap for the storage
  137.      of LongString data.
  138.  
  139.           NOTE: Because of the way in which LongStringType is defined,
  140.      if the ShLngStr unit is recompiled, range checking MUST be turned
  141.      off ({$R-}). Note also that redefining the lsData field as
  142.      array[1..MaxLongString] is apt to cause other problems. This
  143.      redefinition is definitely NOT RECOMMENDED!
  144.      ______________________________
  145.  
  146.        LongString      = ^LongStringType;
  147.  
  148.           The type expected as actual parameters to the routines in
  149.      this unit; also, the type returned by most of the functions.
  150.      ______________________________
  151.  
  152.        lsCompType      = (Less, Equal, Greater);
  153.  
  154.           The type returned by the LongString comparison functions.
  155.      ______________________________
  156.  
  157.        DelimSetType  = set of char;
  158.  
  159.           The type of the set of characters which the GetNext routines
  160.      will use as word delimiters.
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.                                    - 3 -
  171.  
  172.  
  173.  
  174.      VARIABLES AND TYPED CONSTANTS
  175.  
  176.        RingSize : byte = 25;
  177.  
  178.           The number of elements in the ring buffer, used to store
  179.      pointers returned by function calls of type LongString. This
  180.      value may be freely increased to a maximum value of 100 during
  181.      program execution, if necessary. Decreasing it, however, could
  182.      result in orphan blocks allocated on the heap, with no way to
  183.      recover them.
  184.      ______________________________
  185.  
  186.        DelimSet  : DelimSetType = [#0..#32];
  187.  
  188.           The typed constant used by the GetNext routines to determine
  189.      the end of a substring to be returned. It may be freely changed
  190.      during program execution.
  191.  
  192.  
  193.      NOMENCLATURE
  194.  
  195.           All interfaced routines in ShLngStr have "ls" as the first
  196.      two characters of their name.
  197.  
  198.           In the descriptive listings which follow, all routines hav-
  199.      ing similar functionality are grouped, and all routines within a
  200.      group have names which differ only in their respective suffixes;
  201.      e.g.,
  202.  
  203.                      lsDelAll
  204.                      lsDelAllF
  205.                      lsDelAllStr
  206.                      lsDelAllStrF
  207.                      lsDelAllUC
  208.                      lsDelAllUCF
  209.                      lsDelAllStrUC
  210.                      lsDelAllStrUCF
  211.  
  212.           These routines delete all occurrences of an entity from a
  213.      LongString. The basic procedure, lsDelAll, takes three parameters
  214.      of type LongString; respectively, the input LongString containing
  215.      the data to be scanned, the input LongString containing the
  216.      entity to be deleted from the first, and the output LongString
  217.      which is a copy of the input data LongString with all occurrences
  218.      of the second parameter deleted.
  219.  
  220.           The "F" suffixes on the second, fourth, sixth, and eighth
  221.      names indicate a function call returning the output LongString.
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.                                    - 4 -
  229.  
  230.  
  231.  
  232.           The "Str" suffix on the third, fourth, seventh, and eighth
  233.      names indicates that the entity to be deleted is a string rather
  234.      than a LongString.
  235.  
  236.           The "UC" suffix on the fifth through the eighth names
  237.      indicate that searching and deletion will be performed all in
  238.      upper case; the searching will not be case sensitive.
  239.  
  240.           Some functions exist which do not have the "F" suffix. In
  241.      each such case, the returned value is a normal Turbo Pascal data
  242.      type, specifically, WORD or STRING.
  243.  
  244.           In the following, the ordering is alphabetic by primary
  245.      routine name.
  246.  
  247.  
  248.      INTERFACED ROUTINES
  249.  
  250.      lsCENTER
  251.  
  252.      Declarations:
  253.      procedure lsCenter(A : LongString; Width : word; B : LongString);
  254.      function lsCenterF(A : LongString; Width : word)  : LongString;
  255.  
  256.      Purpose:
  257.           Return a LongString centered in a LongString of blanks with
  258.      specified width.
  259.  
  260.      Examples:
  261.           If             A contains "abcdefg"
  262.           then           lsCenter(A, 13, B);
  263.           results in     B containing "   abcdefg   "
  264.  
  265.      Comments:
  266.           If the length of A already exceeds Width, A will be returned
  267.      unchanged.
  268.  
  269.      See Also:
  270.           lsCenterCh
  271.      ______________________________
  272.  
  273.  
  274.  
  275.  
  276.  
  277.  
  278.  
  279.  
  280.  
  281.  
  282.  
  283.  
  284.  
  285.  
  286.                                    - 5 -
  287.  
  288.  
  289.  
  290.      lsCENTERCH
  291.  
  292.      Declarations:
  293.      procedure lsCenterCh(A : LongString; Ch : Char;
  294.                              Width : word; B : LongString);
  295.      function lsCenterChF(A : LongString; Ch : Char;
  296.                              Width : word) : LongString;
  297.  
  298.      Purpose:
  299.           Return a LongString centered in a LongString of Ch with spe-
  300.      cified width.
  301.  
  302.      Examples:
  303.           If             A contains "abcdefg"
  304.           then           lsCenterCh(A, '+', 13, B);
  305.           results in     B containing "+++abcdefg+++"
  306.  
  307.      Comments:
  308.           If the length of A already exceeds Width, A will be returned
  309.      unchanged.
  310.  
  311.      See Also:
  312.           lsCenter
  313.      ______________________________
  314.  
  315.      lsCHARSTR
  316.  
  317.      Declarations:
  318.      procedure lsCharStr(Ch : Char; Len : word; A : LongString);
  319.      function lsCharStrF(Ch : Char; Len : word) : LongString;
  320.  
  321.      Purpose:
  322.           Return a LongString of length Len filled with Ch.
  323.  
  324.      Examples:
  325.           The call       lsCharStr('+', 10, A);
  326.           results in     A containing "++++++++++"
  327.  
  328.      Comments:
  329.           If Len is greater than the maximum length of A, the returned
  330.      LongString will be equal in length to the maximum length of A.
  331.  
  332.      See Also:
  333.      ______________________________
  334.  
  335.  
  336.  
  337.  
  338.  
  339.  
  340.  
  341.  
  342.  
  343.  
  344.                                    - 6 -
  345.  
  346.  
  347.  
  348.      lsCOMP
  349.  
  350.      Declaration:
  351.      function lsComp(A1, A2 : LongString) : lsCompType;
  352.  
  353.      Purpose:
  354.           Compares A1 to A2, returning LESS, EQUAL, or GREATER.
  355.  
  356.      Examples:
  357.              For a normal COMPARE,
  358.                      case lsComp(LS1, LS2) of
  359.                        LESS    : {Do This}
  360.                        EQUAL   : {Do That}
  361.                        GREATER : {Do The Other}
  362.                        end; {case lsComp}
  363.  
  364.              For a case-insensitive COMPARE,
  365.                      case lsComp(lsUpcaseF(LS1), lsUpcaseF(LS2)) of
  366.                        LESS    : {Do This}
  367.                        EQUAL   : {Do That}
  368.                        GREATER : {Do The Other}
  369.                        end; {case lsComp}
  370.  
  371.      Comments:
  372.           This function completely implements the analog of the string
  373.      comparison operators of Turbo Pascal.
  374.  
  375.      See Also:
  376.      ______________________________
  377.  
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.                                    - 7 -
  403.  
  404.  
  405.  
  406.      lsCONCAT
  407.  
  408.      Declarations:
  409.      procedure lsConcat(A, B, C : LongString);
  410.      function lsConcatF(A, B : LongString) : LongString;
  411.      procedure lsConcatLs2Str(S : string; A : LongString;
  412.                                              C : LongString);
  413.      function lsConcatLs2StrF(S : string; A : LongString)
  414.                                              : LongString;
  415.      procedure lsConcatStr2Ls(A : LongString; S : string;
  416.                                              C : LongString);
  417.      function lsConcatStr2LsF(A : LongString; S : string)
  418.                                              : LongString;
  419.  
  420.      Purpose:
  421.           Concatenate the second parameter to the end of the first.
  422.  
  423.      Examples:
  424.           If             A contains "abcdefg"
  425.           and            B contains "hijklmn"
  426.           then           lsConcat(A, B, C);
  427.           results in     C containing "abcdefghijklmn"
  428.  
  429.      Comments:
  430.  
  431.      See Also:
  432.      ______________________________
  433.  
  434.  
  435.  
  436.  
  437.  
  438.  
  439.  
  440.  
  441.  
  442.  
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460.                                    - 8 -
  461.  
  462.  
  463.  
  464.      lsCOPY
  465.  
  466.      Declarations:
  467.      procedure lsCopy(A  : LongString; Start, Len  : word;
  468.                                              B : LongString);
  469.      function lsCopyF(A  : LongString;
  470.                          Start, Len  : word)  : LongString;
  471.  
  472.      Purpose:
  473.           Return a LongString substring of A. The substring begins at
  474.      position Start of A and will be of length Len.
  475.  
  476.      Examples:
  477.           If             A contains "abcdefg"
  478.           then           lsCopy(A, 4, 3, B);
  479.           results in     B containing "def"
  480.  
  481.           If             A contains "abcdefg"
  482.           then           lsCopy(A, 4, 10, B);
  483.           results in     B containing "defg"
  484.  
  485.      Comments:
  486.           Start=1 for first char in A.
  487.  
  488.           If Start > lsLength(A), an empty LongString will be
  489.      returned.
  490.  
  491.           If Start+Len exceeds the length of A, the returned
  492.      LongString will be of length lsLength(A)-Start+1.
  493.  
  494.      See Also:
  495.      ______________________________
  496.  
  497.  
  498.  
  499.  
  500.  
  501.  
  502.  
  503.  
  504.  
  505.  
  506.  
  507.  
  508.  
  509.  
  510.  
  511.  
  512.  
  513.  
  514.  
  515.  
  516.  
  517.  
  518.                                    - 9 -
  519.  
  520.  
  521.  
  522.      lsCOUNT
  523.  
  524.      Declarations:
  525.      function lsCount(A, Obj : LongString):  word;
  526.      function lsCountStr(A : LongString; Obj : string) : word;
  527.      function lsCountStrUC(A : LongString; Obj : string) : word;
  528.      function lsCountUC(A, Obj : LongString):  word;
  529.  
  530.      Purpose:
  531.           Returns the total number of occurrences of Obj in A.
  532.  
  533.      Examples:
  534.           if lsCountStrUC(MyLS, 'abc') <> NotFound then {Do something}
  535.  
  536.           If             A contains "abcdeabcdeabcde"
  537.           and            Obj contains "BCD"
  538.           then           lsCount(A, Obj)
  539.           returns        NotFound ( = 0 )
  540.           but            lsCountUC(A, Obj)
  541.           returns        3
  542.  
  543.      Comments:
  544.           If Obj is not a substring of A, returns NotFound (i.e., 0).
  545.  
  546.      See Also:
  547.      ______________________________
  548.  
  549.  
  550.  
  551.  
  552.  
  553.  
  554.  
  555.  
  556.  
  557.  
  558.  
  559.  
  560.  
  561.  
  562.  
  563.  
  564.  
  565.  
  566.  
  567.  
  568.  
  569.  
  570.  
  571.  
  572.  
  573.  
  574.  
  575.  
  576.                                   - 10 -
  577.  
  578.  
  579.  
  580.      lsDELALL
  581.  
  582.      Declarations:
  583.      procedure lsDelAll(A, Obj, B : LongString);
  584.      function lsDelAllF(A, Obj : LongString):  LongString;
  585.      procedure lsDelAllStr(A : LongString; Obj : string;
  586.                                              B : LongString);
  587.      function lsDelAllStrF(A : LongString;
  588.                                    Obj : string) : LongString;
  589.      procedure lsDelAllStrUC(A : LongString; Obj : string;
  590.                                    B : LongString);
  591.      function lsDelAllStrUCF(A : LongString;
  592.                                    Obj : string) : LongString;
  593.      procedure lsDelAllUC(A, Obj, B : LongString);
  594.      function lsDelAllUCF(A, Obj : LongString):  LongString;
  595.  
  596.      Purpose:
  597.           Deletes all occurrences of Obj in A.
  598.  
  599.      Examples:
  600.           See below.
  601.  
  602.      Comments:
  603.           Should the deletion of Obj from A result in a new occurrence
  604.      of Obj in A, the new occurrence will not be deleted, e.g.,
  605.  
  606.           If             A contains 'aabcbcabcd'
  607.           and            Obj contains 'abc'
  608.           then           lsDelAll(A, Obj, B);
  609.           results in     B containing 'abcd'
  610.           and not        'd'
  611.  
  612.           To delete all occurrences including such incidental
  613.      occurrences, one would use, e.g.,
  614.  
  615.                          repeat
  616.                            lsDelAll(A, Obj, A);
  617.                            until lsCount(A, Obj) = 0;
  618.  
  619.      See Also:
  620.           lsRepAll   lsCount
  621.      ______________________________
  622.  
  623.  
  624.  
  625.  
  626.  
  627.  
  628.  
  629.  
  630.  
  631.  
  632.  
  633.  
  634.                                   - 11 -
  635.  
  636.  
  637.  
  638.      lsDELETE
  639.  
  640.      Declarations:
  641.      procedure lsDelete(A : LongString; Start, Len : word; B :
  642.      LongString);
  643.      function lsDeleteF(A  : LongString; Start, Len  : word)
  644.                                                   : LongString;
  645.  
  646.      Purpose:
  647.           Delete Len characters of A, starting at position Start.
  648.  
  649.      Examples:
  650.           If             A contains "abcdefg"
  651.           then           lsDelete(A, 4, 3, B);
  652.           results in     B containing "abcg"
  653.  
  654.           If             A contains "abcdefg"
  655.           then           lsDelete(A, 4, 10, B);
  656.           results in     B containing "abc"
  657.  
  658.      Comments:
  659.           If Start is greater than the length of A, B = A on output.
  660.  
  661.      See Also:
  662.           lsDelAll   lsRepAll
  663.      ______________________________
  664.  
  665.      lsDISPOSE
  666.  
  667.      Declaration:
  668.      procedure lsDispose(var A : LongString);
  669.  
  670.      Purpose:
  671.           Dispose of A, releasing its heap space.
  672.  
  673.      Examples:
  674.           The call       lsDispose(A);
  675.           results in     All heap space associated with A is released
  676.           and            A = nil
  677.  
  678.      Comments:
  679.  
  680.      See Also:
  681.           lsInit
  682.      ______________________________
  683.  
  684.  
  685.  
  686.  
  687.  
  688.  
  689.  
  690.  
  691.  
  692.                                   - 12 -
  693.  
  694.  
  695.  
  696.      lsGETNEXT
  697.  
  698.      Declarations:
  699.      procedure lsGetNext(LS1, LS2  : LongString);
  700.      function lsGetNextF(LS1 : LongString) : LongString;
  701.      procedure lsGetNextStr(LS1  : LongString; var S2  : string);
  702.      function lsGetNextStrF(LS1  : LongString) : string;
  703.  
  704.      Purpose:
  705.           Returns the next substring of LS1 which is delimited by a
  706.      member of DelimSet.
  707.  
  708.      Examples:
  709.           If             A contains "abc def ghi jkl"
  710.           then the two calls
  711.                          lsGetNext(A, B);
  712.                          lsGetNext(A, B);
  713.           result in      A containing " ghi jkl"
  714.           and            B containing "def"
  715.  
  716.      Comments:
  717.           On return, LS1 is returned untrimmed, but with the first
  718.      matching substring deleted.
  719.  
  720.      See Also:
  721.      ______________________________
  722.  
  723.  
  724.  
  725.  
  726.  
  727.  
  728.  
  729.  
  730.  
  731.  
  732.  
  733.  
  734.  
  735.  
  736.  
  737.  
  738.  
  739.  
  740.  
  741.  
  742.  
  743.  
  744.  
  745.  
  746.  
  747.  
  748.  
  749.  
  750.                                   - 13 -
  751.  
  752.  
  753.  
  754.      lsINIT
  755.  
  756.      Declaration:
  757.      function lsInit(var A  : LongString; L : word)  : boolean;
  758.  
  759.      Purpose:
  760.           "Declares" a LongString of maximum declared length L and
  761.      establishes space for it on the heap.
  762.  
  763.      Examples:
  764.           The call       if lsInit(A, 750) then {Do something};
  765.           results in     a. A returned function value of "true"
  766.                          b. 754 bytes being allocated on the heap.
  767.                             (750 bytes for the character string,
  768.                              4 overhead bytes.)
  769.                          c. A containing a pointer to the heap space.
  770.  
  771.           The call       lsInit(A, 65518);   {MaxLongString = 65517}
  772.           results in     a. A returned function value of "false"
  773.                          b. No space allocation on the heap.
  774.                          c. A = nil
  775.  
  776.      Comments:
  777.           Returns false if L is greater than MaxLongString.
  778.  
  779.           If there is insufficient heap space to accommodate the
  780.      LongString, the program will terminate with a run-time error of
  781.      250 (if lsInit has been called directly) or 251 (if lsInit has
  782.      been called while attempting to allocate space on the ring
  783.      buffer.
  784.  
  785.      See Also:
  786.           lsDispose
  787.      ______________________________
  788.  
  789.  
  790.  
  791.  
  792.  
  793.  
  794.  
  795.  
  796.  
  797.  
  798.  
  799.  
  800.  
  801.  
  802.  
  803.  
  804.  
  805.  
  806.  
  807.  
  808.                                   - 14 -
  809.  
  810.  
  811.  
  812.      lsIOFF
  813.  
  814.      Declaration:
  815.      procedure lsIoff;
  816.  
  817.      Purpose:
  818.           Turns I/O checking off during execution of lsReadLn and
  819.      lsWriteLn.
  820.  
  821.      Examples:
  822.                lsIoff;
  823.                lsReadLn(MyFile, MyLS);
  824.                if lsIoResult <> 0 then {Do something}
  825.                lsIon;
  826.  
  827.      Comments:
  828.           lsIoff, lsIon, and lsIoResult MUST be used for LongString
  829.      I/O operations in place of $I-, $I+, and IoResult.
  830.  
  831.           Emulates at execution time the action of the $I- compiler
  832.      directive, but only for LongString I/O. The default state is
  833.      "on".
  834.  
  835.           If I/O checking is off (either by default or by a call to
  836.      lsIoff), lsIoResult MUST be called after each call to lsReadLn or
  837.      lsWriteLn. If I/O checking is on, and if an I/O error occurs, the
  838.      program will terminate with a run-time error. This action
  839.      duplicates the action of the IoResult function for normal I/O.
  840.  
  841.      See Also:
  842.           lsIon     lsIoResult
  843.      ______________________________
  844.  
  845.  
  846.  
  847.  
  848.  
  849.  
  850.  
  851.  
  852.  
  853.  
  854.  
  855.  
  856.  
  857.  
  858.  
  859.  
  860.  
  861.  
  862.  
  863.  
  864.  
  865.  
  866.                                   - 15 -
  867.  
  868.  
  869.  
  870.      lsION
  871.  
  872.      Declaration:
  873.      procedure lsIon;
  874.  
  875.      Purpose:
  876.           Turns I/O checking on during execution of lsReadLn and
  877.      lsWriteLn.
  878.  
  879.      Examples:
  880.                lsIoff;
  881.                lsReadLn(MyFile, MyLS);
  882.                if lsIoResult <> 0 then {Do something}
  883.                lsIon;
  884.  
  885.      Comments:
  886.           lsIoff, lsIon, and lsIoResult MUST be used for LongString
  887.      I/O operations in place of $I-, $I+, and IoResult.
  888.  
  889.           Emulates at execution time the action of the $I+ compiler
  890.      directive, but only for LongString I/O. The default state is
  891.      "on".
  892.  
  893.           If I/O checking is off (either by default or by a call to
  894.      lsIoff), lsIoResult MUST be called after each call to lsReadLn or
  895.      lsWriteLn. If I/O checking is on, and if an I/O error occurs, the
  896.      program will terminate with a run-time error. This action
  897.      duplicates the action of the IoResult function for normal I/O.
  898.  
  899.      See Also:
  900.           lsIoff    lsIoResult
  901.      ______________________________
  902.  
  903.  
  904.  
  905.  
  906.  
  907.  
  908.  
  909.  
  910.  
  911.  
  912.  
  913.  
  914.  
  915.  
  916.  
  917.  
  918.  
  919.  
  920.  
  921.  
  922.  
  923.  
  924.                                   - 16 -
  925.  
  926.  
  927.  
  928.      lsIORESULT
  929.  
  930.      Declaration:
  931.      function lsIoResult : word;
  932.  
  933.      Purpose:
  934.           Returns the IoResult of the last lsReadLn or lsWriteLn
  935.      performed, and clears the internal variable used to store the
  936.      value.
  937.  
  938.      Examples:
  939.                lsIoff;
  940.                lsReadLn(MyFile, MyLS);
  941.                if lsIoResult <> 0 then {Do something}
  942.                lsIon;
  943.  
  944.      Comments:
  945.           lsIoff, lsIon, and lsIoResult MUST be used for LongString
  946.      I/O operations in place of $I-, $I+, and IoResult.
  947.  
  948.           If I/O checking is off (either by default or by a call to
  949.      lsIoff), lsIoResult MUST be called after each call to lsReadLn or
  950.      lsWriteLn. If I/O checking is on, and if an I/O error occurs, the
  951.      program will terminate with a run-time error. This action
  952.      duplicates the action of the IoResult function for normal I/O.
  953.  
  954.      See Also:
  955.           lsIoff    lsIon
  956.      ______________________________
  957.  
  958.  
  959.  
  960.  
  961.  
  962.  
  963.  
  964.  
  965.  
  966.  
  967.  
  968.  
  969.  
  970.  
  971.  
  972.  
  973.  
  974.  
  975.  
  976.  
  977.  
  978.  
  979.  
  980.  
  981.  
  982.                                   - 17 -
  983.  
  984.  
  985.  
  986.      lsINSERT
  987.  
  988.      Declarations:
  989.      procedure lsInsert(A, Obj : LongString; Start : word;
  990.                                              B : LongString);
  991.      function lsInsertF(A, Obj : LongString; Start : word)
  992.                                              : LongString;
  993.      procedure lsInsertStr(A : LongString; Obj : string;
  994.                            Start : word; B : LongString);
  995.      function lsInsertStrF(A : LongString; Obj : string;
  996.                            Start : word) : LongString;
  997.  
  998.      Purpose:
  999.           Insert Obj into A at position Start returning a new
  1000.      LongString.
  1001.  
  1002.      Examples:
  1003.           If             A contains "abcdef"
  1004.           and            Obj contains "ABC"
  1005.           then           lsInsert(A, Obj, 4, B);
  1006.           results in     B containing "abcABCdef"
  1007.  
  1008.      Comments:
  1009.           If Start > lsLength(A), no action is taken.
  1010.  
  1011.      See Also:
  1012.           lsDelete
  1013.      ______________________________
  1014.  
  1015.      lsLEFTPAD
  1016.  
  1017.      Declarations:
  1018.      procedure lsLeftPad(A : LongString; Len : word; B : LongString);
  1019.      function lsLeftPadF(A : LongString; Len : word) : LongString;
  1020.  
  1021.      Purpose:
  1022.           Left-pad the LongString in A to length Len with blanks,
  1023.      returning a new LongString.
  1024.  
  1025.      Examples:
  1026.           If             A contains "abc"
  1027.           then           lsLeftPad(A, 2, B);
  1028.           results in     B containing "  abc"
  1029.  
  1030.      Comments:
  1031.           If Len < lsLength(A), A is returned truncated without
  1032.      padding.
  1033.  
  1034.      See Also:
  1035.           lsLeftPadCh     lsPad           lsPadCh
  1036.      ______________________________
  1037.  
  1038.  
  1039.  
  1040.                                   - 18 -
  1041.  
  1042.  
  1043.  
  1044.      lsLEFTPADCH
  1045.  
  1046.      Declaration:
  1047.      procedure lsLeftPadCh(A : LongString; Ch : Char; Len : word;
  1048.                                                      B : LongString);
  1049.      function lsLeftPadChF(A : LongString; Ch : Char; Len : word)
  1050.                                                      : LongString;
  1051.  
  1052.      Purpose:
  1053.           Left-pad the LongString in A to length Len with Ch,
  1054.      returning a new LongString.
  1055.  
  1056.      Examples:
  1057.           If             A contains "abc"
  1058.           then           lsLeftPad(A, '+', 2, B);
  1059.           results in     B containing "++abc"
  1060.  
  1061.      Comments:
  1062.  
  1063.      See Also:
  1064.           lsLeftPad       lsPad           lsPadCh
  1065.      ______________________________
  1066.  
  1067.      lsLENGTH
  1068.  
  1069.      Declaration:
  1070.      function lsLength(A : LongString) : word;
  1071.  
  1072.      Purpose:
  1073.           Return the length of a LongString. A must have been
  1074.      initialized.
  1075.  
  1076.      Examples:
  1077.           If             A contains "Cogito, ergo sum."
  1078.           then           lsLength(A)
  1079.           returns        17
  1080.  
  1081.      Comments:
  1082.  
  1083.      See Also:
  1084.      ______________________________
  1085.  
  1086.  
  1087.  
  1088.  
  1089.  
  1090.  
  1091.  
  1092.  
  1093.  
  1094.  
  1095.  
  1096.  
  1097.  
  1098.                                   - 19 -
  1099.  
  1100.  
  1101.  
  1102.      lsLOCASE
  1103.  
  1104.      Declaration:
  1105.      procedure lsLocase(A, B : LongString);
  1106.      function lsLocaseF(A  : LongString) : LongString;
  1107.  
  1108.      Purpose:
  1109.           Locase the LongString in A, returning a new LongString.
  1110.  
  1111.      Examples:
  1112.           If             A contains "ABCdefGHIjkl"
  1113.           then           lsLocase(A, B);
  1114.           results in     B containing "abcdefghijkl"
  1115.  
  1116.      Comments:
  1117.  
  1118.      See Also:
  1119.           lsUpcase
  1120.      ______________________________
  1121.  
  1122.      lsLONGSTRING2STR
  1123.  
  1124.      Declaration:
  1125.      function lsLongString2Str(A : LongString) : string;
  1126.  
  1127.      Purpose:
  1128.           Convert a LongString to a Turbo string.
  1129.  
  1130.      Examples:
  1131.           If             A (LongString) contains "abcdef"
  1132.           then           lsLongString2Str(A)
  1133.           returns        'abcdef' (string)
  1134.  
  1135.      Comments:
  1136.           If lsLength(A) > 255, the returned string will be truncated
  1137.      to length 255.
  1138.  
  1139.      See Also:
  1140.           lsStr2LongString
  1141.      ______________________________
  1142.  
  1143.  
  1144.  
  1145.  
  1146.  
  1147.  
  1148.  
  1149.  
  1150.  
  1151.  
  1152.  
  1153.  
  1154.  
  1155.  
  1156.                                   - 20 -
  1157.  
  1158.  
  1159.  
  1160.      lsPAD
  1161.  
  1162.      Declarations:
  1163.      procedure lsPad(A : LongString; Len : word; B : LongString);
  1164.      function lsPadF(A : LongString; Len : word) : LongString;
  1165.  
  1166.      Purpose:
  1167.           Right-pad the LongString in A to length Len with blanks,
  1168.      returning a new LongString.
  1169.  
  1170.      Examples:
  1171.           If             A contains "abc"
  1172.           then           lsPad(A, 5, B);
  1173.           results in     B containing "abc  "
  1174.  
  1175.           but if         lsInit(C, 5) = true
  1176.           then           lsPad(A, 8, C);
  1177.           also results in  C containing "abc  "
  1178.  
  1179.      Comments:
  1180.  
  1181.      See Also:
  1182.           lsPadCh         lsLeftPad       lsLeftPadCh
  1183.      ______________________________
  1184.  
  1185.      lsPADCH
  1186.  
  1187.      Declarations:
  1188.      procedure lsPadCh(A : LongString; Ch : Char; Len : word;
  1189.                                              B : LongString);
  1190.      function lsPadChF(A : LongString; Ch : Char; Len : word)
  1191.                                              : LongString;
  1192.  
  1193.      Purpose:
  1194.           Right-pad the LongString in A to length Len with Ch,
  1195.      returning a new LongString.
  1196.  
  1197.      Examples:
  1198.           If             A contains "abc"
  1199.           then           lsPadCh(A, '+', 5, B);
  1200.           results in     B containing "abc++"
  1201.  
  1202.           but if         lsInit(C, 5) = true
  1203.           then           lsPadCh(A, '+', 8, C);
  1204.           also results in  C containing "abc++"
  1205.  
  1206.      Comments:
  1207.  
  1208.      See Also:
  1209.           lsPad           lsLeftPad       lsLeftPadCh
  1210.      ______________________________
  1211.  
  1212.  
  1213.  
  1214.                                   - 21 -
  1215.  
  1216.  
  1217.  
  1218.      lsPOS
  1219.  
  1220.      Declarations:
  1221.      function lsPos(Obj, A : LongString) : word;
  1222.      function lsPosStr(Obj : string; A : LongString) : word;
  1223.      function lsPosUC(Obj, A : LongString) : word;
  1224.      function lsPosStrUC(Obj : string; A : LongString) : word;
  1225.  
  1226.      Purpose:
  1227.           Return the position of Obj in A, returning NotFound if not
  1228.      found.
  1229.  
  1230.      Examples:
  1231.           If             A contains "abcdeabcdeabcde"
  1232.           and            Obj contains "BCD"
  1233.           then           lsPos(A, Obj)
  1234.           returns        NotFound ( = 0 )
  1235.           but            lsPosUC(A, Obj)
  1236.           returns        2
  1237.  
  1238.      Comments:
  1239.  
  1240.      See Also:
  1241.      ______________________________
  1242.  
  1243.  
  1244.  
  1245.  
  1246.  
  1247.  
  1248.  
  1249.  
  1250.  
  1251.  
  1252.  
  1253.  
  1254.  
  1255.  
  1256.  
  1257.  
  1258.  
  1259.  
  1260.  
  1261.  
  1262.  
  1263.  
  1264.  
  1265.  
  1266.  
  1267.  
  1268.  
  1269.  
  1270.  
  1271.  
  1272.                                   - 22 -
  1273.  
  1274.  
  1275.  
  1276.      lsREADLN
  1277.  
  1278.      Declaration:
  1279.      procedure lsReadLn(var F : Text; A : LongString);
  1280.  
  1281.      Purpose:
  1282.           Read a LongString from a text file.
  1283.  
  1284.      Examples:
  1285.           lsReadLn(MyFile, A);
  1286.  
  1287.      Comments:
  1288.           If the "declared" length of A (set by lsInit) is less than
  1289.      the actual length of the line in the text file, the incoming
  1290.      string will be truncated to the "declared" length of A and the
  1291.      file will be positioned at the beginning of the next line (the
  1292.      exact analog of a normal Turbo PASCAL string ReadLn).
  1293.  
  1294.           If I/O checking is not off (either by default or by a call
  1295.      to lsIoff), lsIoResult MUST be called after each call to lsReadLn
  1296.      or lsWriteLn. If I/O checking is on, and if an I/O error occurs,
  1297.      the program will terminate with a run-time error. This action
  1298.      duplicates the action of the IoResult function for normal I/O.
  1299.  
  1300.      See Also:
  1301.           lsIoff    lsIon     lsIoResult     lsWriteLn
  1302.      ______________________________
  1303.  
  1304.  
  1305.  
  1306.  
  1307.  
  1308.  
  1309.  
  1310.  
  1311.  
  1312.  
  1313.  
  1314.  
  1315.  
  1316.  
  1317.  
  1318.  
  1319.  
  1320.  
  1321.  
  1322.  
  1323.  
  1324.  
  1325.  
  1326.  
  1327.  
  1328.  
  1329.  
  1330.                                   - 23 -
  1331.  
  1332.  
  1333.  
  1334.      lsREPALL
  1335.  
  1336.      Declarations:
  1337.      procedure lsRepAll(A, Obj, Obj1, B : LongString);
  1338.      function lsRepAllF(A, Obj, Obj1 : LongString):  LongString;
  1339.      procedure lsRepAllStr(A : LongString; Obj, Obj1 : string;
  1340.                                                      B : LongString);
  1341.      function lsRepAllStrF(A : LongString; Obj, Obj1 : string)
  1342.                                                      : LongString;
  1343.      procedure lsRepAllStrUC(A : LongString; Obj, Obj1 : string;
  1344.                                                      B : LongString);
  1345.      function lsRepAllStrUCF(A : LongString; Obj, Obj1 : string)
  1346.                                                      : LongString;
  1347.      procedure lsRepAllUC(A, Obj, Obj1, B : LongString);
  1348.      function lsRepAllUCF(A, Obj, Obj1 : LongString):  LongString;
  1349.  
  1350.      Purpose:
  1351.           Replaces all occurrences of Obj in A with Obj1.
  1352.  
  1353.      Examples:
  1354.           If             A contains 'aabcbcabcd'
  1355.           and            Obj contains 'abc'
  1356.           and            Obj1 contains '12345'
  1357.           then           lsRepAll(A, Obj, Obj1, B);
  1358.           results in     B containing 'a12345bc12345d'
  1359.  
  1360.      Comments:
  1361.           Should the replacement of Obj by Obj1 in A result in a new
  1362.      occurrence of Obj in A, the new occurrence will not be replaced.
  1363.      To do so, except under rather unusual conditions, could result in
  1364.      a non-terminating condition.
  1365.  
  1366.      See Also:
  1367.           lsDelAll
  1368.      ______________________________
  1369.  
  1370.  
  1371.  
  1372.  
  1373.  
  1374.  
  1375.  
  1376.  
  1377.  
  1378.  
  1379.  
  1380.  
  1381.  
  1382.  
  1383.  
  1384.  
  1385.  
  1386.  
  1387.  
  1388.                                   - 24 -
  1389.  
  1390.  
  1391.  
  1392.      lsSIZEOF
  1393.  
  1394.      Declaration:
  1395.      function lsSizeOf(A : LongString) : word;
  1396.  
  1397.      Purpose:
  1398.           Returns the total heap space required for A, including the
  1399.      two control words. A must have been initialized.
  1400.  
  1401.      Examples:
  1402.           See below.
  1403.  
  1404.      Comments:
  1405.           lsSizeOf MUST be used to determine the effective size of a
  1406.      LongString. Any attempt to use SizeOf(A) will return a value of
  1407.      4; any attempt to use SizeOf(A^) will return a value of 5.
  1408.      Neither is particularly informative!
  1409.  
  1410.           Remember that, just as
  1411.                            SizeOf(StringVariable)
  1412.      returns a value one greater than the declared length of
  1413.      StringVariable, so
  1414.                         lsSizeOf(LongStringVariable)
  1415.      will return a value four greater than the "declared" length of
  1416.      LongStringVariable.
  1417.  
  1418.           If A has not been initialized, the results are
  1419.      unpredictable.
  1420.  
  1421.      See Also:
  1422.           lsLength
  1423.      ______________________________
  1424.  
  1425.  
  1426.  
  1427.  
  1428.  
  1429.  
  1430.  
  1431.  
  1432.  
  1433.  
  1434.  
  1435.  
  1436.  
  1437.  
  1438.  
  1439.  
  1440.  
  1441.  
  1442.  
  1443.  
  1444.  
  1445.  
  1446.                                   - 25 -
  1447.  
  1448.  
  1449.  
  1450.      lsSTR2LONGSTRING
  1451.  
  1452.      Declarations:
  1453.      procedure lsStr2LongString(S : string; A : LongString);
  1454.      function lsStr2LongStringF(S : string)  : LongString;
  1455.  
  1456.      Purpose:
  1457.           Convert a Turbo string into a LongString.
  1458.  
  1459.      Examples:
  1460.           If             S (string) contains "abcdef"
  1461.           then           lsStr2LongString(S, A);
  1462.           results in     A (LongString) containing "abcdef"
  1463.  
  1464.      Comments:
  1465.  
  1466.      See Also:
  1467.           lsLongString2Str
  1468.      ______________________________
  1469.  
  1470.      lsTRANSFER
  1471.  
  1472.      Declaration:
  1473.      procedure lsTransfer(A, B : LongString);
  1474.  
  1475.      Purpose:
  1476.           Transfers the contents of A into B.
  1477.  
  1478.      Examples:
  1479.           B^ := A^;
  1480.           INCORRECT!! This construct will give unpredictable but guar-
  1481.      anteed incorrect results.
  1482.  
  1483.           lsTransfer(A, B);
  1484.           Correct. ALWAYS use lsTransfer to move the contents of one
  1485.      LongString into another.
  1486.  
  1487.      Comments:
  1488.  
  1489.      See Also:
  1490.      ______________________________
  1491.  
  1492.  
  1493.  
  1494.  
  1495.  
  1496.  
  1497.  
  1498.  
  1499.  
  1500.  
  1501.  
  1502.  
  1503.  
  1504.                                   - 26 -
  1505.  
  1506.  
  1507.  
  1508.      lsTRIM
  1509.  
  1510.      Declarations:
  1511.      procedure lsTrim(A, B : LongString);
  1512.      function lsTrimF(A  : LongString) : LongString;
  1513.  
  1514.      Purpose:
  1515.           Return a LongString with leading and trailing white space
  1516.      removed.
  1517.  
  1518.      Examples:
  1519.           If             A contains "  Cogito, ergo sum.      "
  1520.           then           lsTrim(A, B);
  1521.           results in     B containing "Cogito, ergo sum."
  1522.  
  1523.      Comments:
  1524.           "White space" is any sequence of characters in the range
  1525.      #0..#32.
  1526.  
  1527.      See Also:
  1528.           lsTrimLead      lsTrimTrail
  1529.      ______________________________
  1530.  
  1531.      lsTRIMLEAD
  1532.  
  1533.      Declarations:
  1534.      procedure lsTrimLead(A, B : LongString);
  1535.      function lsTrimLeadF(A  : LongString): LongString;
  1536.  
  1537.      Purpose:
  1538.           Return a LongString with leading white space removed.
  1539.  
  1540.      Examples:
  1541.           If             A contains "  Cogito, ergo sum.      "
  1542.           then           lsTrimLead(A, B);
  1543.           results in     B containing "Cogito, ergo sum.      "
  1544.  
  1545.      Comments:
  1546.           "White space" is any sequence of characters in the range
  1547.      #0..#32.
  1548.  
  1549.      See Also:
  1550.           lsTrim          lsTrimTrail
  1551.      ______________________________
  1552.  
  1553.  
  1554.  
  1555.  
  1556.  
  1557.  
  1558.  
  1559.  
  1560.  
  1561.  
  1562.                                   - 27 -
  1563.  
  1564.  
  1565.  
  1566.      lsTRIMTRAIL
  1567.  
  1568.      Declarations:
  1569.      procedure lsTrimTrail(A, B : LongString);
  1570.      function lsTrimTrailF(A : LongString) : LongString;
  1571.  
  1572.      Purpose:
  1573.        Return a LongString with trailing white space removed.
  1574.  
  1575.      Examples:
  1576.           If             A contains "  Cogito, ergo sum.      "
  1577.           then           lsTrimTrail(A, B);
  1578.           results in     B containing "  Cogito, ergo sum."
  1579.  
  1580.      Comments:
  1581.           "White space" is any sequence of characters in the range
  1582.      #0..#32.
  1583.  
  1584.      See Also:
  1585.           lsTrim          lsTrimLead
  1586.      ______________________________
  1587.  
  1588.      lsUPCASE
  1589.  
  1590.      Declaration:
  1591.      procedure lsUpcase(A, B : LongString);
  1592.      function lsUpcaseF(A  : LongString) : LongString;
  1593.  
  1594.      Purpose:
  1595.           Upcase the LongString in A, returning a new LongString.
  1596.  
  1597.      Examples:
  1598.           If             A contains "ABCdefGHIjkl"
  1599.           then           lsUpcase(A, B);
  1600.           results in     B containing "ABCDEFGHIJKL"
  1601.  
  1602.      Comments:
  1603.  
  1604.      See Also:
  1605.           lsLocase
  1606.      ______________________________
  1607.  
  1608.  
  1609.  
  1610.  
  1611.  
  1612.  
  1613.  
  1614.  
  1615.  
  1616.  
  1617.  
  1618.  
  1619.  
  1620.                                   - 28 -
  1621.  
  1622.  
  1623.  
  1624.      lsWRITELN
  1625.  
  1626.      Declaration:
  1627.      procedure lsWriteLn(var F : Text; A : LongString);
  1628.  
  1629.      Purpose:
  1630.           Write a LongString to a text file.
  1631.  
  1632.      Examples:
  1633.           lsWriteLn(MyFile, A);
  1634.  
  1635.      Comments:
  1636.           If I/O checking is not off (either by default or by a call
  1637.      to lsIoff), lsIoResult MUST be called after each call to lsReadLn
  1638.      or lsWriteLn. If I/O checking is on, and if an I/O error occurs,
  1639.      the program will terminate with a run-time error. This action
  1640.      duplicates the action of the IoResult function for normal I/O.
  1641.  
  1642.      See Also:
  1643.           lsIoff    lsIon     lsIoResult     lsReadLn
  1644.      ______________________________
  1645.  
  1646.  
  1647.  
  1648.  
  1649.  
  1650.  
  1651.  
  1652.  
  1653.  
  1654.  
  1655.  
  1656.  
  1657.  
  1658.  
  1659.  
  1660.  
  1661.  
  1662.  
  1663.  
  1664.  
  1665.  
  1666.  
  1667.  
  1668.  
  1669.  
  1670.  
  1671.  
  1672.  
  1673.  
  1674.  
  1675.  
  1676.  
  1677.  
  1678.                                   - 29 -
  1679.  
  1680.